错误描述

此问题的由来是因为某天看用 asciidoctor-maven-plugin 生成的 swagger html 文档时, 发现有个链接没法跳转到指定的 header.如下图所示:

经过排查发现是因为 ApiModel 的 value 包含 / 时会出现问题.以上面的问题为例, 写了一个简单的示例, 如下:

Controller 有一个方法:

1
2
3
4
5

@RequestMapping(value= "...", method = RequestMethod.POST)
@ApiOperation(value="...", notes="...")
public BaseResponse createOrder(@Valid @RequestBody Order request, BindingResult bindingResult) {
	return null;
}

Order 类定义如下:

1
2
3
4
5

// 带有斜线 /
@ApiModel("order/create_order")
public class Order {
    ...
}

错误排查

首先查看生成的 html 文件:

1
2
3
4
5

// 跳转链接的 ID 是 _create_order
<p><a href="#_create_order">create_order</a></p>

// ID 是 _order_create_order, 而不是 _create_order
<h3 id="_order_create_order">order/create_order</h3>

进一步排查生成的 .adoc 文件.在 paths.adoc、definitions.adoc 文件中搜索 create_order 相关的信息.

paths.adoc 内容如下:

1
2
3
4
5
6
7
8

==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**request** +
__required__|request|<<_create_order,create_order>>
|===

definitions.adoc 内容如下:

1
2

[[_order_create_order]]
=== order/create_order

很明显, 这两个 ID 是不一样的.就导致了生成的 html 文档也有问题.

这会导致如下两个问题:

• 链接无法跳转到指定的 header
• 请求/响应示例无法生成

错误原因分析

针对上面的两个问题, 分别做下错误原因分析:

• 链接无法跳转到指定的 header: GenericRef 类有两个属性, ref 和 simpleRef.以上面的例子为例(order/create_order), ref 是 #/definitions/order/create_order, simpleRef 是 create_order.simpleRef 不包含 order 前缀.所以在生成链接 id 的时候, 可能是一个使用了 simpleRef, 另外一个使用了 ref, 所以应该统一使用其中一个.

• 请求/响应示例无法生成: Swagger#getDefinitions() 方法返回的是 Map<String, Model>, 这个 map 里面包含了 /order/create_order, 但是不包含 create_order, 所以当生成示例的时候, 可能是使用的 simpleRef 从 map 中获取 Model 对象(此时肯定获取不到).如果使用 ref(去除 #/definitions/ 前缀)可以从 map 中获取 Model 对象, 所以应该先使用 simpleRef, 如果获取不到 Model, 再使用 ref.

• 感谢您的阅读，本文由 ykgarfield 版权所有。如若转载，请注明出处：ykgarfield
• 文章链接: https://ykgarfield.github.io/2019/01/01/文档工具/swagger/Swagger2Markup bug-生成的 html 文档有问题当 ApiModel value 包含斜线/